Screen area and sizes

The screen in AppCUI is a 2D matrix of characters, with different widths (w) and heights (h).

It is important to note that each character is going to have the same size. For each character we have the following attributes:

• Forenground color (the color of the character that we are printing)
• Background color (the color of the character background)
• Attributes: Bold, Italic, Underline, Boxed

The following collors are supported by AppCUI via Color enum from AppCUI::graphics module:

Besides this list, a special enuma variant Color::Transparent can be used to draw without a color (or in simple terms to keep the existing color). For example, if the current character has a forenground color Red writing another character on the same position with color Transparent will keep the color Red for the character.

Additionally, if the TRUE_COLORS feature is enabled, the following variant is supported:

• Color::RGB(r, g, b) - this is a custom color that is defined by the RGB values.

REMARKS:

1. Not all terminals support this exact set of colors. Further more, some terminals might allow changing the RGB color for certain colors in the pallete.
2. Enabling TRUE_COLORS feature does not mean that the terminal supports 24-bit colors. It only means that the AppCUI framework will use 24-bit colors for the screen, but the terminal might still need to convert them to the terminal's color pallete.
3. Enabling TRUE_COLORS feature will make the size of the Color enum to be 4 bytes (instead of 1 byte without this feature). If memory is a concern and you don't need true colors, it is recommended to NOT enable this feature.

The list of attributes available in AppCUI are described by CharFlags enum from AppCUI::graphics module and include the following flags:

• Bold - bolded character
• Underline - underlined character
• Italic - italic character
• DoubleUnderline - a character that is undelined twice
• CurlyUnderline - a character with a curly underline
• DottedUnderline - a character with a dotted undeline
• StrikeThrough - strike through character

These flags can be used with | operator if you want to combine them. For example: CharFlags::Bold | CharFlags::Underline means a character that is both bolded and underlined.

Character

As previously explained, a character is the basic unit of AppCUI (we can say that it is similar to what a pixel is for a regular UX system). The following method can be used to build a character:

pub fn new<T>(code: T, fore: Color, back: Color, flags: CharFlags) -> Character

where:

• fore and back are characters colors (foreground and background)
• code can be a character (like 'a' or 'b') or a value of type SpecialCharacter that can be used to quickly access special characters (like arrows). Any type of UTF-8 character is allowed.
• flags are a set of flags (like Bold, Underline, ...) that can be used.

The list of all special characters that are supported by AppCUI (as described in the SpacialCharacter enum) are:

Box lines and corners

Arrows

Blocks

Other

Other character constructors

Besides Character::new(...) the following constructors are also available:

1.  pub fn with_char<T>(code: T) -> Character
   

   this is the same as calling:

   Character::new(code, Color::Transparent, Color::Transparent, CharFlags::None)
   

2.  pub fn with_color(fore: Color, back: Color) -> Character
   

   this is the same as calling:

   Character::new(0, fore, fore, CharFlags::None)
   

   Note: Using the character with code 0 means keeping the existing character but chainging the colors and attributes.

Macro builds

You can also use char! macro to quickly create a character. The macro supports tha following positional and named parameters:

and the named parameters:

The following values can be used as color parameters for foreground and background parameters:

For Transparent color you can use the following values: transparent, invisible or ?.

You can also specify special characters by either using their specific name from the enum SpecialChars or by using certaing adnotations as presented in the following table:

Character attributes

Sometimes, you might want to use a character with a specific color and attributes. For example, you might want to use a bolded character with a red color on a yellow background. This is in particular useful when building a theme where you just select the attributes and colors and then apply them to the characters. AppCUI provides a specific structure called CharAttribute that allows you to define colors and attributes for a character. To create a CharAttribute you can use the following methods:

impl CharAttribute {
    pub fn new(fore: Color, back: Color, flags: CharFlags) -> CharAttribute {...}
    pub fn with_color(fore: Color, back: Color) -> CharAttribute {...}
    pub fn with_fore_color(fore: Color) -> CharAttribute {...}
    pub fn with_back_color(back: Color) -> CharAttribute {...}
}

or the macro charattr! that works similar to char! but it returns a CharAttribute object. The macro supports tha following positional and named parameters:

and the named parameters:

Examples

Example 1: Letter A with a Red color on an Yellow background:

Character::new('A',Color::Red,Color::Yellow,CharFlags::None)

or

char!("A,red,yellow")

or

char!("A,r,y")

Example 2: Letter A (bolded and underlined) with a White color on a Dark blue background:

Character::new('A',Color::White,Color::DarkBlue,CharFlags::Bold | CharFlags::Underline)

or

char!("A,fore=White,back=DarkBlue,attr=[Bold,Underline]")

or

char!("A,w,db,attr=Bold+Underline")

Example 3: An arrow towards left a Red color while keeping the current background:

Character::new(SpecialCharacter::ArrowLeft,Color::Red,Color::Transparent,CharFlags::None)

or

char!("ArrowLeft,fore=Red,back=Transparent")

or

char!("<-,red")

or

char!("<-,r")

Example 4: An arrow towards left a DarkGreen color, Bolded and Underlined while keeping the current background. We will use a CharAttribute for this example:

let attr = CharAttribute::new(Color::DarkGreen,Color::Transparent,CharFlags::Bold | CharFlags::Underline);  
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr);

or

let attr = charattr!("DarkGreen,Transparent,attr:Bold+Underline");
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr));

or

let attr = charattr!("dg,?,attr:Bold+Underline");
let c = Character::with_attr(SpecialCharacter::ArrowLeft,attr);